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General 

This product can be used to aid in the conversion o&elocatable object 
modules to a Z80 source code file. It consists of three utilities : UNREL, 
DECODREL, and SPLLTLIB. UNREL will decode a relocatable object module which 
has been assembled by either Microsoft's M80 or MISOSYS' MRAS assemblers . The 
output is an assembler source file compatible with MRAS and one which should 
also be equally usable with M80. DECODREL can be used to obtain a bit— stream 
analysis of a REL module or library . Finally, SPLITLIB can be used to break a 
large REL library into smaller pieces suitable for loading into memory 
constrained REL Librarians (so that your librarian can extract single modules 
to be UNRELed) . 

This documentation provides information on both the UNREL— T80 product (usable 
on a TRS-80 with either LDOS (TM) 5.x or LS-DOS (TM) 6.x) and the UNREL-CP/M 
product (usable with CP/M 2.x or 3.x). Although file specifications are shown 
in this document in the form, filename&xt : d under CP/M this will be assumed 
to represent the form, d: filename . ext The CP/M version requires a Z80 based 
computer . 
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The files on the accompanying DATA diskette may be easily copied to your 
working SYSTEM disk by means of the DOS COPY (or PIP) utility. There may be a 
file named "README/TXT" on the disk. If so, that file will contain important 
information which may not appear in this printed documentation. You should 
read this file by issuing the command: LIST README or TYPE README.TXT. 

UNREL - REL to ASM translator 



UNREL will decode a relocatable object module which has been assembled by 
either Microsoft's M80 or MISOSYS ' MRAS assemblers . The output is an ASCII 
assembler source file using Z80 mnemonics. Invoke UNREL with the syntax: 



I 



UNREL in file [/REL] [out file [/ASM] ] / 

infile - Is the filename of the REL module. If 
the extension is omitted, 'REL' will 
be assumed. 

outfile - Is the name to be used for the output 
Z80 assembler file. If omitted, then 
'Infile/ASM" will be used. If outfile / 
is entered without an extension, 'ASM' 
will be assumed. The source drive will 
be used unlessoutfile includes a / 

drive specification. 



The action of UNREL is to take a binary REL file 
displayed in hexadecimal : 



which looks like this when 



80 91D15391D4 942045053455481 9414 9154D155205504F494E5481 131253 
916054C494E454281 9312539150 91A0553455458598194D455161654A064 
44F424F584 681 9113D1D4 94 1220 6424F584C494E819113D3125391 605584 
4454C548156511153152064745545058598151D15516166054E4547484C8 
1521311 9111 6034444548115925155E06475250434C3180D0D314E500001 



into a form more usable by your MRAS 
the following: 



or M80 assembler; an ASCII file such as 



;GENGRP/ASM:1 

NAME ( ' GENGRP ' ) 

BAKCLR, CLIPP, DCOMPR, DOWNC, FCERR, FETCHC, FORCLR, GRPACX 
GKPACY, GXPOS, GYPOS, ICOMP , LEFTC, LINSTL, MAPXYC, MAXDEL 
MAXUPD, MINDEL, MINUPD, NSETCX, PGRPCX, PGRPC, READC, RIGHTC 
SCALXY, SCNCRD, SEEGRP , SETATR, SETC, STOREC, UPC, VIEWMP 
VXLEFT, VXRGHT, VYLEFT, VYRGHT, XCHGAC, XCHGX, XCHGY 
BOXLLN, CLS, DDT, DOBOXF, DOGRPH, DOLINE, GETPXY 
GRPCL1 , HLFDE, LINE, LINEB, LINEBF, NEGHL, POINT 
PSET, SETXY, SETXYR, VIEW, XDELT, YDELT 



EXTRN 
EXTRN 
EXTRN 
EXTRN 
EXTRN 
PUBLIC 
PUBLIC 
PUBLIC 
CSEG 
SETXYR : 

PUSH 
PUSH 
LD 
LD 



DE 

HL 
HL, (GRPACX) 
(PGRPCX) , HL 
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EX 


(SP) , HL 


LD 


E, (HL) 


INC 


HL 


LD 


D, (HL) 


POP 


HL 


ADD 


HL,DE 


LD 


(GRPACX) , HL 


LD 


(GXPOS) , HL 


LD 


HL, (GRPACY) 


LD 


(PCRPCY) , HL 


EX 


(SP) , HL 


LD 


E, (HL) 


INC 


HL 


LD 


D, (HL) 


POP 


HL 


ADD 


HL,DE 


LD 


(GRPACY) , HL 


LD 


(GYPOS) , HL 


RET 




SETXY: 





The example above, incidentally, is from the graphics library, GRPLIB/REL, 
which is distributed with Tandy's hi res graphics board. This miraculous 
transformation is made possible by the UNREL utility. Of course, there are 
limitations . 

First, UNREL makes the assumptions that anything in a code segment is code, 
and anything in a data segment is data. Those of you already having experience 
with object code disassemblers know that decoders can sometimes get "fooled" 
by data being interpreted as code. With object module REL files, this problem 
still exists. However, if good programming practices, such as segregation of 
code and data, have been followed by the original programmer of the REL 
module, your decoding job is simpler. 

Second, UNREL supports only the following special link items (SLI) : 

- entry symbol 

1 - select common block 

2 - program name 

3 - request library search 

5 - define common size 

6 - chain external 

7 - define entry point 
9 - extern+offset 

10 - define data size 

11 - set location counter 

13 - define program size 

14 — end program 

15 — end file 

The undocumented special link items (4 and 8) as well as chain address, SLI- 
12, are not supported. The later is used in Microsoft's one-pass compilers. 
SLI— 4 and SLI— 8 are used in a more recent version of M80 for handling 8-bit 
externs with greater support of arithmetic expressions resolvable at link 
time; however, Microsoft wasn 't too potent in letting the world know of the 
specific details associated with that link item. In any event, we're not 
supporting it in UNKEL . 
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Here is a small sample program used to demonstrate the behavior of UNREL. It is 
the assembly listing using MRAS . 

mras testmod: 1 

MRAS 1.0a - Copyright (c) 1985 MTSOSYS, Inc., All rights reserved. 



Including TESTMOD :1 






00001 


CSEG 


0000' 210000" 


00002 START 


LD 


0003 ' 3E0A 


00003 


LD 


0005 ' EF 


00004 


RST 


0006' C30000* 


00005 


JP 




00006 


DSEG 


0000" 48 


00007 MESSAGE 


DB 


65 6C 6C 


6F 20 77 6F 72 




6C 64 21 


OD 




0000' 


00008 


END 


0000 is the transfer address 




00000 Total errors 




36974 Free space 





HL, MESSAGE 
A, 10 
28H 
NEXT## 

* Hello World! ' ,13 



START 



Note that this module contains an external symbol, "NEXT". It also contains 
both a code and a data segment. There are also two symbols local to the 
module; one in each segment. We can process the resulting REL module with 
UNREL using a command such as: 

UNREL TESTMOD 

UNREL will generate the file, TESTMOD/ASM, which contains the assembler source 
code for "testmod" as determined from its relocatable object module. During 
the translation process, UNREL will display some messages which indicate its 
progress . These messages will look like the following: 

UNREL - Disassemble /REL Module - Version 1.0b 

Copyright 1987 Riclin Computer Products . All rights reserved. 

Pass 1 - building segments and symbol tables 

Pass 2 — resolving relocations and local labels 

Pass 3 - disassembling to output 



After this operation, UNREL has generated the source file which can then be 
assembled by either M80 or MRAS (or other M80- compatible assembler) . The 
"assembler source" file would look like this: 

; TESTMOD/ASM: 1 



NAME 


( s TESTM 


EXTRN 


NEXT 


CSEC, 




CSEG$0000: 




LD 


HL,DSEG$0000 


LD 


A, OAH 


RST 


28H 


JP 


NEXT 


DSEG 
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DSEGSOOOO: 

DB 48H 

DB 65H 

DB 6CH 

DB 6CH 

DB 6FH 

DB 2 OH 

DB 77H 

DB 6FH 

DB 72H 

DB 6CH 

DB 64H 

DB 21H 

DB ODH 

END CSEG$0000 

As can be observed, the external symbol has been noted by means of an "EXTRN" 
statement. The source code prologue section will include all such externals 
and PUBLIC symbols as well. Symbols local to the module will be identified by 
a unique symbol. The data segment region will be generated as discrete byte 
values . 

In cases where the original assembler source module was fraught with non-code 
fragments in the code segment or code fragments in the data or common 
segments, UNREL will not be able to generate an "accurate" representation of 
the original code. This is to be expected. Also, UNREL will group all code 
segments into one single code segment. Similarly, all data segments will be 
grouped into one. This does not effect the logic of the original source code. 

UNREL can work properly only on a single module; don't expect it to produce 
meaningful output if you try to ihnrel". a library composed of more than one 
module. If you have the MISOSYS librarian for M-80 type REL files, MLIB, or a 
CP/M librarian, such as LIB80 or LIB, you can easily pull apartrelocatable 
libraries into their individual module members and then translate the 
associated modules into ASM source. Without the resources of a librarian, you 
may be able to split a library into single modules with the SPLITLIB utility 
provided as part of this package. 
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DECODREL - REL bit stream analysis 

The DECODREL utility generates an analysis of the bit stream of a REL file. 
This can be used to more fully understand the actual bit stream. DECODREL is 
invoked with the syntax: 



DECODREL [-f] infile[/REL] [out file [/RMP] ] 

-f - Flag used to designate a FULL output 

versus a brief output. DECODREL will 
default to brief. Specify "-f" for a 
FULL report . 

infile - Is the filename of the REL module. If 
the extension is omitted, 'REL' will 
be assumed. 

outfile - Is the name to be used for the output 
analysis file. If omitted, Then 
'Infile/RMP" will be used. If outfile 
is entered without an extension, 'RMP ' 
will be assumed. The source drive will 
be used unlessoutfile includes a 
drive specification. 



If we want to process the TESTMOD/REL module previously illustrated, 
generate an analysis map, we would use a command such as: 

DECODREL TESTMOD 



and 



The following analysis is generated to the file named, " TESTMOD /RMP " : 



0000: 
0007: 
OOOA : 
OOOD: 
001 A: 
002C:2 
0034:6 
0038:7 



7 
:5 
■4 
;3 
■0 



Program name (02) , TESTMO 
Data area size (OA) , Absolute (O) , OOOD 
Program size (OD) , Program relative (1) , 0009 
Set counter (OB), Program relative (1) , 0000 
Set counter (OB) , Data relative (2) , 0000 
Chain external (06), Program relative (1) , 0007, 
End program (OE) , Program relative (1) , 0000 
End file (OF) 



NEXT 



Since we did not specify the "-F" flag, the BRIEF analysis is generated. Such 

an analysis does not include any absolute, data relative, code relative, or 

common relative bytes. The presentation includes the bit— stream flow of 
special link items. 

The first field noted is the relative byte and bit offset of the referenced 
item within the relocatable object module file (remember, bits are used hi — 
order to lo— order or 7 to 0) . This may prove useful for specialized purposes . 
The information presented on each line describes the special link item by 
name; the contents of (and description where appropriate) each SLI field is 
also noted in hexadecimal. The technical specification section describes the 
structure of an M80-compatible relocatable object module. That section should 
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be reviewed if you are either unfamiliar with that format or have, at most, 
read only sketchy details of the format. 

If you would prefer the DECODREL analysis to include information on the entire 
REL module bit stream, the preceding command invocation would be changed to: 

DECODREL -F TESTMOD ALLDATA 

This example also illustrates the specification of dvtfile" . The following 
analysis is generated to the file named, "ALLDATA/RMP" : 



0000:7 


- 


Program name (02) 


i , TESTMO 




0007:5 


- 


Data area size (OA) , Absolute (O) , OOOD 




000A-.4 


- 


Program size (OD) 


>, Program relative (1) , 0009 




000D-.3 


- 


Set counter (OB) , 


Program relative (1) , 0000 




0010:2 


- 


0000' 


- Absolute 


item, 


21 




0011:1 


- 


0001 ' 


- Data relative 


(2), 0000 




0014:6 


- 


0003' 


- Absolute 


item, 


3E 




0015:5 


- 


0004 ' 


- Absolute 


item, 


OA 




0016:4 


- 


0005' 


- Absolute 


item, 


EF 




0017:3 


- 


0006' 


- Absolute 


item, 


C3 




0018:2 


- 


0007' 


- Absolute 


item, 


00 




0019:1 


- 


0008' 


- Absolute 


item, 


00 




001A-.0 


- 


Set counter (OB) , 


Data 


relative 92), 0000 




001E-.7 


- 


0000" 


- Absolute 


item, 


48 




001F-.6 


- 


0001" 


- Absolute 


item, 


65 




0020:5 


- 


0002" 


- Absolute 


item, 


6C 




0021:4 


- 


0003" 


- Absolute 


item, 


6C 




0022:3 


- 


0004" 


- Absolute 


item, 


6F 




0023:2 


- 


0005" 


- Absolute 


item, 


20 




0024:1 


- 


0006" 


- Absolute 


item, 


77 




0025:0 


- 


0007" 


- Absolute 


item, 


6F 




0027:7 


- 


0008" 


- Absolute 


item, 


72 




0028:6 


- 


0009" 


- Absolute 


item, 


6C 




0029:5 


- 


OOOA" 


- Absolute 


item, 


64 




002A-.4 


- 


OOOB" 


- Absolute 


item, 


21 




002B-.3 


- 


OOOC" 


- Absolute 


item, 


OD 




002C:2 


- 


Chain 


external (06), Program relative (1) , 0007, NEXT 




0034:6 


- 


End program (OE) , 


Program relative (1) , 0000 




0038:7 




End file (OF) 








analysi 


.s 


includes the segment relative address of each 


item being 



presented followed by the standard segment indicator character. 
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SPLITLIB - REL library splitter 

Librarians which work by loading a REL library into a memory buffer may limit 
the size of the library it can deal with. This is the case with MLIB. , To 
overcome this limitation, SPLITLIB can be used to split a large library file 
into two or more smaller files. SPLITLIB is invoked with the syntax: 



SPLITLIB in file [/REL] maxlength [drivespec] 



infile 



maxlength - 



I 
I 
I 
I 
I 
I 
I 
I 
I 
I 

I 
I 
drivespec - This designates the drive to which the / 
file partitions will be written . If / 

omitted, the drive specified with / 

'infile" will be used. Each output / 

partition will be named, i'nfile/Rxx" ; / 
xx" being 01, 02, . . . for the first, / 
second, etc., partitions . / 



Is the filename of the REL library . If 
the extension is omitted, 'REL ' will 
be assumed. 

Is the maximum length of an output 
file (in bytes) . The module currently 
being output will be continued to it 's 
"module end" which will be followed by 
an "end file" byte (X' 9E ') Maxlength \ 
must be in the range <100-32767) . 



Let's say we have a library named GRPLIB that we wish to split. The following 
example illustrates splitting this library file into pieces approximately 6000 
bytes in length: 

slibd grplib:! 6000 :1 

SPLITLIB - Split /REL Library - Version 1.0a 

Copyright 1986 Riclin Computer Products . All rights reserved. 

Reading input file GRPLIB/REL: 7 

Writing output file GRPLIB/R01 : 1 
Module ADVGRP 
Module GENGRP 

Writing output file GRPLIB/R02 : 1 
Module TRSGRP 



This example illustrates how SPLITLIB informs you of the file it is reading, 
the output files being generated, and the modules being written to each output 
file partition . 

If the last module of the source file being written to the last output 
partition results in a partition size exceedingnaxlength, another file of 
NULL length will be generated. This NULL file can be ignored. 
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Technical specifications 

This section describes the relocatable bit stream of a Microsoft relocatable 
object module. We do not intend this section to be an authority on the 
subject; however, its discussion accurately portrays our interpretation of the 
documentation appearing in the literature presented by Microsoft. 

Microsoft compatible 'REL ' format 

All Z80 assemblers work in a similar fashion, in that they convert a file 
containing SOURCE CODE, written in Z80 assembly language mnemonics, to OBJECT 
CODE in some binary format. In ABSOLUTE assemblers, this binary data is a 
faithful representation of the actual machine language (ones and zeros) that 
the Z80 will execute when you want your program to run. This object code can 
only load and execute at a FIXED address in the Z80 ' s memory space. On the 
other hand, a RELOCATABLE assembler, such as M80 or MRAS, will generate object 
code which can be relocated to any address in the Z80's 64K memory space 
before the program is to be executed. 

Let's look at an example of absolute assembly . The following program has been 
assembled at an ORIGIN of 0100H. Notice especially the values assigned to the 
memory addresses @DATE, @EXIT, @DSPLY, START, and BUFFER: 



0100 






00100 






ORG 


0100H 




4470 


00110 


@DATE 




EQU 


447 OH 






40 2D 






00120 


@EXIT 


EQU 


402DH 




4467 






00130 


(3DSPLY 


EQU 


4467H 




OOOD 






00140 


CR 




EQU 


ODH 




0100 


211401 




00150 


START: 


LD 


HL, BUFFER 




0103 


CD7044 




00160 






CALL 


@DATE 




0106 


3E0D 




00170 






LD 


A,CR 




0108 


321C01 




00180 






LD 


(BUFFER+8) ,A 




010B 


211401 




00190 






LD 


HL, BUFFER 




010E 


CD6744 




00200 






CALL 


@DSPLY 




0111 


C32D40 




00210 






JP 


@EXIT 




0114 






00220 


BUFFER : 


DS 


9 




0100 






00230 






END 


START 




@DATE 


4470 @DSPLY 




4467 


' @EXIT 


40 2D 


BUFFER 


0114 CR 






OOOD 


' START 


0100 



The program has been reassembled below at a new origin, 0200H. Some of the 
addresses for the above labels have changed, while some remain the same: 



0200 




00100 




ORG 


0200H 


4470 




00110 


@DATE 


EQU 


447 OH 


40 2D 




00120 


@EXIT 


EQU 


402DH 


4467 




00130 


@DSPLY 


EQU 


4467H 


OOOD 




00140 


CR 


EQU 


ODH 


0200 


211402 


00150 


START: 


LD 


HL, BUFFER 


0203 


CD7044 


00160 




CALL 


QDATE 


0206 


3E0D 


00170 




LD 


A,CR 


0208 


321C02 


00180 




LD 


(BUFFER+8) , A 


02 OB 


211402 


00190 




LD 


HL, BUFFER 


02 OE 


CD6744 


00200 




CALL 


QDSPLY 


0211 


C 3 2D 40 


00210 




JP 


QEXIT 


0214 




00220 


BUFFER : 


DS 


9 



0200 
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00230 END START 



@DATE 
BUFFER 



4470 @DSPLY 
0214 CR 



4467 @EXIT 
OOOD START 



40 2D 
0200 



To be specific, START and BUFFER have changed, while the others aren 
changed. Both START and BUFFER have been relocated! START, Instead of being at 
0100H is now at 0200H, and BUFFER has moved from 0114H to 0214H. This offset 
of 0100H is due to the changed origin, 0100H versus 0200H. START and BUFFER 
are therefore internally relocatable values, while @DATE, for example, will 
always be 447 OB, and is thus known as an absolute value. 

The same program, as assembled using relocation looks like this: 



4470 








QDATE 


EQU 447 OH 




40 2D 








@EXIT 


EQU 402DH 




4467 








@DSPLY 


EQU 4467H 




OOOD 








CR 


EQU ODH 




0000' 


21 


0014 ' 




START: 


LD HL, BUFFER 




0003' 


CD 


4470 






CALL QDATE 




0006' 


3E 


OD 






LD A, CR 




0008' 


32 


001C 






LD (BUFFER+8) , A 




OOOB' 


21 


0014 ' 






LD HL, BUFFER 




OOOE' 


CD 


4467 






CALL @DSPLY 




0011 ' 


C3 


40 2D 






JP @EXIT 




0014' 








BUFFER: 


DS 9 

END START 




@DATE 




4470 


@DSPLY 


4467 @EXIT 


40 2D 


BUFFER 


0014 ' 


CR 




OOOD START 


0000 



All of the internal program addresses have been assembled as if the program had 
an origin of OOOOH, and are noted with a following single-quote ('). This is 
relocation at work. The binary output of this assembly (a /REL file) cannot be 
executed by the Z80 until you choose an origin for the program; this is done 
by a utility known as a LINKER, and can be ANY address in the Z80 memory space. 
The linker will determine, from the origin you have selected, where START and 
BUFFER really will be when the program is run. If you choose 0100H as the 
origin, then START will be located at 0100H, and BUFFER at 0114H. Other origins 
will produce similar results; START and BUFFER will be at different addresses, 
but the offset between them (0014H) will always be the same. 



This characteristic of relocatable object files, that they can be LINKED at 
any origin, is extended by a further capability: relocatable object files may 
be linked TOGETHER to form a complete program from many smaller pieces. This 
allows you to write a very large program in lesser chunks which are easier to 
edit and to understand. In addition, you can develop libraries of standard and 
useful subroutines, each thoroughly tested and debugged, which any main 
program may call upon when necessary. The Microsoft FORTRAN library 

(FORLIB/REL) , for example, thus contains many subroutines which can be used by 
any FORTRAN or Z80 assembler program. 

The mechanism of program and subroutine linkage that is often used is 
implemented by the ENTRY and EXTERNAL attributes . A label which is declared 
ENTRY (or GLOBAL or PUBLIC) in one module can be accessed by another module in 
the following way: 



; Module 1 




ENTRY 


L ABE LI 


LABEL1 : 




<code 


follows> 


END 




; Module 2 




EXTRN 


L ABE LI 


CALL 


L ABE LI 


END 
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;this is an entry point 
; end of module 1 



;this is an EXTERNAL declaration 

; could also be EXT. 

; and this is a reference to the 

/external 

; end of module 2 

The relocatable format also allows you to do other things. In many 
applications , program code and data areas must be separated. This most often 
occurs when code must be placed in ROM, such as the BASIC interpreter in a 
TRS-80. However, the data areas cannot be in ROM; they must be iorriteable 
memory (RAM), and thus must be separated from the code areas. This can be 
accomplished by use of the CSEG and DSEG commands to the assembler. A CSEG 
pseudo-operation signals the start of a code area, while a DSEG indicates the 
start of a data area. Code and data SEGMENTS may be intermixed in a program 
source file, and the assembler will automatically keep them separate by the 
use of two distinct program or location counters, one for each segment . When 
you link a program with the linker, you may tell the linker at what address to 
place the code, and also where to place the data. Thus the two segments are 
separated. The above example is shown below using this technique: 



4470 






@DATE EQU 


447 OH 


40 2D 






@EXIT EQU 


402DH 


4467 






@DSPLY 


EQU 


4467H 


OOOD 






CR 


EQU 


ODH 


0000 ' 






CSEG ; code starts here 


0000' 


21 0000" 


START: 


LD 


HL, BUFFER 


0003' 


CD 


4470 




CALL 


@DATE 


0006' 


3E 


OD 


LD 


(BUFFER+8) , A 


0008' 


32 


0008" 




LD 


HL, BUFFER 


OOOB' 


21 


0000" 




CALL 


@DSPLY 


OOOE' 


CD 


4467 




JP 


@EXIT 


0011 ' 


C3 


40 2D 




DSEG 


; data starts here 








BUFFER : 


DS 


9 


0000" 








END 


START 


@DATE 




4470 


@DSPLY 


4467 


@EXIT 40 2D 


BUFFER 




0000" 


CR 


OOOD 


START 0000 ' 



Notice how the label BUFFER is now located at OOOOH, but in the data segment, 
as indicated by the double-quote (") following the address . An linker session 
(illustrated with MLINK commands) could then be as follows with user entries 
in BOLDFACE: 



DOS Ready 

MLINK 

MLINK - Ver 1.0a Copyright 1985 MISOSYS, Inc. 

?-p=100 

?-d=1000 

?test 

2 7937 Free space 



All rights reserved 
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P <0100-0113 0014> D <1000-1008 0009> 

*test-n-e 

DOW Ready 

The "-p" command to the linker established the program (or code) segment 
origin, while the "—d" command did the same for the data segment. After 
loading TEST/REL with the next command, the linker then tells us where the two 
segments are located and how long they are. The final command writes out an 
executable command file (/CMD) . If we were to disassemble TEST/CMD, we would 
find that START is located at 0100H and BUFFER at 1000H. Thus the program is 

separated into ROM and RAM sections. 

Relocatable assemblers and linkers have other capabilities , such as the use of 
COMMON blocks. You can also generate absolute code, if you use the ASEG 
pseudo-op . 

Finally, we get to the actual format of a Microsoftrelocatable object file. A 
/REL file is composed of a bit (not byte) stream. Each /REL file may contain a 
table of ENTRY points and EXTERNAL references . Each ENTRY point is identified 
by its name (1 to 7 ASCII characters; although some releases of M80/L80 
support only 1-6) and its relative location within one of the module's code, 
data, or common segments . Each EXTERNAL reference is identified by its name, 
and also by a chain (or linked list) of pointers, each of which locates the 
relative address within the module where the external was used. The last 
pointer in the chain is zero. The /REL file also contains internal relocation 
data necessary for resolution of label references within the module. All 
external and internal relocatable references are changed to absolute values at 
link time, when the program's segment origins have been established. The 
remainder of the information in the /REL file consists of absolue code and 
data bytes which do not need relocation, and numerous other fields which 
describe common blocks, the module name, the module segment lengths, and the 
/REL file end (or EOF byte) . A library file would contain many such modules, 
each separated by program end indicators, and terminated by an EOF byte. 

Let 's take one Last look at our example, modified slightly, to see what the 
relocatable object file assembled from this source code would look like: 



NAME ( s TEST ' ) 



4470 
40 2D 
4467 
OOOD 



0000' 


21 


0000" 


0003' 


CD 


4470 


0006' 


3E 


OD 


0008' 


32 


0008" 


OOOB' 


21 


0000" 


OOOE' 


11 


0000* 


0011 ' 


01 


0009 


0014 ' 


ED 


BO 


0016' 


21 


0000* 


0019' 


CD 


4467 


001C 


C3 


40 2D 



(3D ATE 


EQU 


447 OH 


@EXIT 


EQU 


402DH 


(3DSPLY 




EQU 4467H 


CR 


EQU 


ODH 




CSEG 


; code starts here 




ENTRY 


START 




EXT 


MESSAGE 


START: 




LD HL, BUFFER 
CALL @DATE 




LD 


A,CR 




LD 


(BUFFER+8) , A 




LD 


HL, BUFFER 




LD 


DE, MESSAGE 

LD BC, BUFFLEN 




LDIR 






LD 


HL, MESSAGE 
CALL @DSPLY 
JP @EXIT 




DSEG 


; data starts here 




ENTRY 


BUFFER 
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0000" 
0009 



BUFFER DS 9 

BUFFLEN EQU $-BUFFER 
END START 



@DATE 

BUFFER 

MESSAGE 



4470 @DSPLY 

0000" BUFFLEN 
0017* START 



4467 
0009 
0000' 



QEXIT402D 
CR OOOD 



Notice how the external label, MESSAGE, is defined in the symbol table; the 
value 0017H represents the relative location of the LAST reference to MESSAGE 
in the assembled code, and the trailing asterisk (") denotes an external 
symbol both in this table and in the assembled code listing. 

The following is a tabular picture of the decoded /REL file. Each column 
represents : 

1. Absolute [0] or relocatable [1] item [1 bit]. If absolute, column (2) 
shows the value in hex [8 bits] . 

2. Relocation type [0 = special link item; 1, 2, or 3 = segment 
relative] [2 bits] . See column (8) . 



3. Special link item control field in decimal [4 bits] . See column (8) . 

4. "A-field" address type, same as column (2) [2 bits]. 

5. "A-field" value, displayed as high/low, but reversed in file [16 
bits] . 

6. "B-field" length [3 bits]. 

7. "B-field" symbol in ASCII [8 bits each character] . 
Description of the object file record as decoded. 

(1) (2) (3) (4) (5) (6) (7) (8) 

10 2 4 TEST program name 

10 5 START entry symbol for library search 

10 6 BUFFER entry symbol for library search 

1 10 00 09 define data area size 

1 13 1 00 IF define program size 

1 Oil 1 00 00 set loading location counter (code) 

21 absolute (1st byte in code segment) 

12 00 00 data relative (ref. to BUFFER) 

CD absolute 

70 absolute 

44 absolute 

3E absolute 

OD absolute 

32 absolute 

12 00 08 data relative (ref. to BUFFER+8) 

21 absolute 

12 00 00 data relative (ref. to BUFFER) 

11 absolute (ref. to MESSAGE follows) 

00 absolute (this plus next byte are 

00 absolute end of external chain) 

01 absolute 
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09 











00 











ED 











BO 











21 











1 






00 OF 





CD 











67 











44 











C3 











2D 











40 








1 





11 


2 


00 00 


1 





11 


2 


00 09 


1 





7 


2 


00 00 6 BUFFER 


1 





6 


1 


00 17 7 MESSAGE 


1 





7 


1 


00 00 5 START 


1 





14 


1 


00 00 


1 





15 







to MESSAGE follows) 
(link in chain) 



absolute 

absolute 

absolute 

absolute 

absolute (ref. 

program relative 

absolute 

absolute 

absolute 

absolute 

absolute 

absolute 
set loading location counter (data) 

set loading location counter (data) 
define entry point (data) 

chain external (head of list) 
define entry point (code) 
end program (force to next byte 

end file marker 



What follows is 
this package. 



a complete definition of the relocation format supported by 



The REL file is an encoded bit-stream containing relocatable object code 
information. It follows the format documented by Microsoft for the M80 
assembler and L80 linker; however, only 16— bit externals are described. 



1) IF the next bit is a zero, 
loaded according to the value of the 
THEN recycle to 1) . 



THEN the following eight bits are 
location counter currently in effect, 



ELSE IF the next bit is a one, 
is interpreted as follows: 



THEN the next two bits represent a code which 



01 - Indicates a code relative value follows, 
loaded after being offset by the code 
recycle to 1) . 



The next 16 bits are 
segment origin, THEN 



10 - Indicates a data relative value follows, 
loaded after being offset by the data 
recycle to 1) . 



The next 16 bits are 
segment origin, THEN 



11 - Indicates a common relative value follows . The next 16 bits are 
loaded after being offset by the selected common segment origin, 
THEN recycle to 1) . 



00 — Indicates a Special Link item. The SL item consists of the 
following four bits which are interpreted as one of 16 different 
items described below; an optional VALUE field which consists of 
a 2-bit address type [00 = absolute, 01 = code relative, 10 = 
data relative, 11 = common relative] and a 16-bit address; and 
an optional NAME field that consists of a 3-bit name length 
followed by the name in 8-bit bytes. SLs 0000-0100 use only a 
NAME field; SLs 0101-1000 use both a VALUE field and a NAME 
field; SLs 1001-1110 use only a VALUE field; SL 1111 has neither 
a NAME nor a VALUE field. Unless otherwise specified, at the 
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conclusion of processing a special link item, processing 
recycles to 1) . The Special Link items are as follows : 

0000 — indicates an entry symbol. This is used by the linker 

only when searching a library to see if the module is 
needed to satisfy an undefined extern. 

0001 - Select Common Block. Used to specify the NAMEd Common 

Block for subsequent common relative references . 

0010 - Module name. This is the name of the module. The first 

one encountered is saved by MLINK for use in generating 
the optional HEADER record of the /CMD file. 

0011 - Request Library Search. The library designated by the 

NAME field will be searched to resolve undefined 
externals prior to any object code generation. An REL 
will be first assumed. If one is not found, an IRL will 
then be assumed. 

0100 - This item is reserved by Microsoft. 

0101 - Define Common Size. This is used by MLZNK to establish 

the size of the common block designated by the NAME 
field. 

0110 - Chain External. The VALUE field contains a pointer to the 

head of a chain which ends with an absolute zero. Each 
16— bit element of the chain will be replaced with the 
value of the external symbol described in the NAME field. 

0111 - Define Entry Point. The VALUE field specifies the value 

of the symbol described by the NAME field. 

1000 - This item is reserved by Microsoft. 

1001 - External plus Offset. This specifies that the VALUE field 

must be added to the following two bytes in the current 
segment after all chain externals have been processed. 

1010 - Define Data Size. The VALUE field is used by the linker 

to establish the size of the data segment of the current 
module . 

1011 - Set Location Counter. The location counter is set to the 

value identified by the VALUE field. 

1100 - Chain Address. The VALUE field contains the the head 

pointer of a linked list; each entry in the list is to be 
replaced by the current value of the location counter. 
Chain address is generated by one-pass assemblers (or 
compilers) to have the linkerfixup forward references . 

1101 - Define Code Size. The VALUE field is used by the linker 

to establish the size of the code segment of the current 
module . 
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1110 - End of Module. The VALUE field defines the transfer 

address for the module if other than absolute zero. This 
item denotes the end of the module. The bit stream is 
also advanced to a byte boundary. Recycle to 1) if 
loading a module from other than a library search. 

1111 - End of File. This is used to indicate the end of the 

file. It is used when searching libraries or when loading 
modules to detect the end of the file. 



Warranty 

This software program (s) is warranted to perform as documented when used on 
the specified hardware operating under the specified disk operating system as 
shown on the accompanying documentation. If within 90 days of the date of 
purchase the program is found to be defective due to a bug in the code, the 
publisher will, upon request, provide a patch to correct the bug or will 
update the program diskette with a corrected copy within a reasonable time 
period after return of the program diskette to the publisher . If within 90 
days of the date of purchase the documentation proves defective due to missing 
pages, the publisher will provide substitutes for the missing pages upon 
request . 

The publisher shall have no liability or responsibility to the purchaser or 
any other person, company, or entity with respect to any liability, loss, or 
damage caused or alleged to have been caused by this product, including but 
not Limited to any interruption of service, loss of business and anticipatory 
profits, or consequential damages resulting from the operation or use of this 
program . 



Customer Support 

Customer service information on this product may be acquired by contacting 
MYSOSYS, Inc., at the following address: 

MYSOSYS, Inc. 

P.O. Box 239 

Sterling, Virginia 22170-0239 

703-450-4181 



